Node / ReticulumProjects / MeshChatX.git / files / docs / agents / skills / deferred-network-startup / SKILL.md

Displaying Raw • View rendered • Download

Tc9d1d9# Skill: deferred-network-startup

Treat HTTP-up as distinct from RNS-ready. Gate UI on Ta5d6ff`/api/v1/status`, return 503 for retryable init failures, and contain RNS panic on Android.

Tc9d1d9## When to use

Tff7b72- Changing boot order, status payload, or loading screens

Tff7b72- Adding APIs that need identity / DB / RNS before answering

Tff7b72- Touching Electron loading probes or Android Chaquopy boot

Tff7b72- Debugging "app loads but mesh is dead" or early 500s during start

Tc9d1d9## Lifecycle facts

Tff7b72- HTTP can bind before RNS / identity finish.

Tff7b72- Ta5d6ff`/api/v1/status` reports Ta5d6ff`starting` / Ta5d6ff`ok` / Ta5d6ff`failed` with Ta5d6ff`stage` and Ta5d6ff`network_ready`.

Tff7b72- Ta5d6ff`starting` is normal, not an error.

Tff7b72- Electron loading probes accept HTTP 200 with Ta5d6ff`starting` or Ta5d6ff`ok`. Do not require Ta5d6ff`network_ready` before first navigation.

Tff7b72- Vue boot uses startup interpreters that can mount recovery UI when Ta5d6ff`failed` still allows degraded UI.

Tff7b72- A browser service worker may serve a cached app shell while Ta5d6ff`/api/v1/status` is unreachable. That is not Ta5d6ff`ui_ready`. Keep gating on status polling.

Tc9d1d9## API behaviour

Tff7b72- Prefer **503** with a retryable message when identity / DB / network is temporarily unavailable.

Tff7b72- Prefer opaque **500** only for unexpected failures after ready.

Tff7b72- CLI one-shots (Ta5d6ff`--self-check`, restore helpers) may still initialize synchronously.

Tc9d1d9## Android / RNS panic

Tff7b72- Ta5d6ff`RNS.panic()` must be contained (Ta5d6ff`rns_startup_recovery.py`). Uncaught Ta5d6ff`os._exit` kills the in-process Android Python host.

Tff7b72- Off-main-thread RNS init cannot register signals. Reinstall handlers on the main loop after ready.

Tc9d1d9## Key files

Tff7b72- Ta5d6ff`meshchatx/meshchat.py` (Ta5d6ff`/api/v1/status`, background RNS init)

Tff7b72- Ta5d6ff`meshchatx/src/frontend/js/networkStartupWait.js`

Tff7b72- Ta5d6ff`electron/loadingStatusProbe.js`

Tff7b72- Ta5d6ff`meshchatx/src/backend/rns_startup_recovery.py`

Tff7b72- Ta5d6ff`meshchatx/src/backend/reticulum_config_guard.py`

Tc9d1d9## Verification

Ta5d6ff```Ta5d6ffbash

uv run pytest tests/backend/test_rns_startup_recovery.py -q --tbTff7b72=short

pnpm Tffa657exec vitest run tests/frontend/networkStartupWait.test.js

uv run python -m meshchatx.meshchat --self-check

Ta5d6ff```